Skip to content
lab components / Tables and lists

Column header

Allow users to understand information in each table column and optionally sort column data for easier data discovery

ExamplesPropertiesGuidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { ColumnHeader } from "@siteimprove/fancylab";

Examples

Basic usage

The basic variant displays the column label in a concise and easily readable manner.

Use cases:

  • When the column's content is readily apparent from its label (e.g., "Name," "Date,").
  • When sorting or additional information is not required.
Table header
Theme: agentic-ai-2025
<ColumnHeader content="Table header" />

Usage with tooltip

A variant with a tooltip provides supplemental information about the column's data. The tooltip appears on hover or focus.

Use cases:

  • When the column label needs clarification or additional context.
  • When explaining abbreviations or specialized terminology.
Table header
Theme: agentic-ai-2025
<ColumnHeader content="Table header" tooltip="Some extra info about the column" />

Usage with sorting

A sortable variant allows users to sort table data in ascending or descending order by clicking on the header. Visual indicators (arrows) signify the current sorting state.

Use cases:

  • When users need to quickly organize and analyze table data.
  • When presenting large datasets that require flexible sorting options.
Theme: agentic-ai-2025
const [direction, setDirection] = useState<"asc" | "desc">("asc"); const currentSort = { property: "property-name" as const, direction: direction }; return ( <ColumnHeader content="Sortable header" sort={currentSort} onSort={() => setDirection(direction === "asc" ? "desc" : "asc")} property="property-name" /> );

Properties

Header
Theme: agentic-ai-2025
PropertyDescriptionDefinedValue
contentRequired
stringContent of the header cell
propertyRequired
stringSortable property
tooltipOptional
| string | objectTooltip to explain the column
sortOptional
| objectProperty and direction the table is currently sorted by
onSortOptional
functionCallback for when a sort button is clicked
defaultSortDirectionOptional
"asc" | "desc"Default direction for sorting the property
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)
tabIndexOptional
numberTab index of the outermost HTML element of the component
onKeyDownOptional
functionCallback for onKeyDown event
onMouseDownOptional
functionCallback for onMouseDown event
onMouseEnterOptional
functionCallback for onMouseEnter event
onMouseLeaveOptional
functionCallback for onMouseLeave event
onFocusOptional
functionCallback for onFocus event
onBlurOptional
functionCallback for onBlur event

Guidelines

Best practices

General

Use ColumnHeader when

  • You want to clearly label and organize data into columns within a table or grid structure.
  • You want to allow users to sort the data based on the values in a particular column.

Placement

ColumnHeader is typically used in the following places:

  • At the top of each column in a Table.
  • In data grids or similar data display structures. e.g Dashboard widgets.

Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your ColumnHeader to existing components for visual consistency.
  • Alignment:
    • Left-align text labels for readability.
    • Consider aligning numeric data to the right for easier comparison.

Interaction

  • Click:
    • Sortable headers should respond to clicks to change the sort order.
    • Tooltips should appear on hover or focus, and disappear on mouse-out or focus loss.
  • Consider how column headers will adapt on smaller screens (e.g., wrapping text).

Do not use when

  • The data isn't naturally organized into columns, and column headers won't be helpful e.g List Table.

Accessibility

For designers

  • Ensure users can navigate to and interact with column headers using the keyboard.
  • Use sufficient color contrast between text and background.
  • Use descriptive tooltip text for screen readers.

For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

Writing

  • Keep labels brief but informative. Aim for 10-20 characters.
  • Use sentence case for labels (e.g., "Last name" not "Last Name").
  • Avoid excessive abbreviations or jargon. For instance, "SEO" for "search engine optimization" might be acceptable, while "CPC" for "cost per conversion" might not be.
  • In tooltip, provide enough context to clarify the column's meaning, but avoid long explanations and links.